Request New Data Commands

Device Communication: Request New Data

Note: This command is supported for Nodes configured with FMS or FMS Legacy data groups. See EFM Data Items for more information.

Request New Data (REQNEWDATA via script) is a Node-level command that triggers the service to retrieve device data since the last successful poll. The type(s) of data requested is configurable via the command parameters. Available data is dependent on the configured device properties, which in turn is related to the types of data available in the associated field device. The types of data that can potentially come back are Periodic Metering (PM) history, Periodic Quality (PQ) history, Events history, Alarms history, Batch data, or Ticket data.

Prior to the initial poll using this command, it is important that you first have current configuration data for the Node, and product data if the Node supports liquid metering. Optionally, the Configuration Request Frequency parameter can be used to request concurrent configuration/product (for liquid metering) data when you run the command. Such requests can be the initial configuration/product data requests made for the Node.

You can optionally configure the command to request the current configuration record on a less frequent specified interval, and/or to timeout if the request is not completed in a specified period of time. Additionally you can configure the command to also include missing data, or both unavailable and missing data, in the request.

Note: If the Request New Data command is configured to request data from a device that it does not support, the FMS will recognize that, and the request will not be sent to the device in question. Only requested command results will be reflected in the Command Results field.

Devices are eligible if the following apply.

Their device record is set to "active"
The associated device record in the DDS is enabled
The user executing the command has the appropriate security access
There are no outstanding data polls of the same type
The field device has at least one new history record

You must have proper security authorization to execute this command. See FMS Security (and CMDDEV security event) for information about configuring security access for FMS commands.

See Configuring Request New Data Commands and Running Node Commands for more information about using this command via FMS Explorer.

See Special FMS Command Notes for more information about requesting alarm and event data.

See Scheduling FMS Command Tasks in the MSS for more information about scheduling commands.

See FMS ActiveX Controls and CxHmiFms for more information about using commands via FMS ActiveX controls on CygNet Studio or CygNet Vision screens.

See CxFms for more information about scripting commands.

Command Definition Properties

The following command definition properties apply to Request New Data commands, when scheduling, creating, or editing commands via CygNet Explorer.

Property	Description
FMS service	Select a Site.Service for the command from the available FMS service list in the drop-down menu.
Command	Select the desired Command name from the drop-down menu. See FMS Commands for more information about available command types.
Time format	Select the desired Time format for the command from the drop-down menu. Options are as follows. Contract Device Default value is Device time. Notes: This parameter determines how the time window is selected in the database; not how the data is exported. For daily devices only, specifying start and end times of midnight (00:00:00), will always be interpreted as Contract time format, regardless of this selected parameter value.
Priority	Select a processing queue Priority for the command from the drop-down menu. Options from least to greatest priority are as follows. Low level Medium level High level User initiated transaction Admin initiated transaction Default value is Low level processing queue priority.
Logging	Select a Logging level for the command results from the drop-down menu. Options are as follows. Low — displays errors Medium — displays errors and warnings High — displays errors, warnings, and status Default value is Low level logging when scheduling a command via the MSS in CygNet Explorer. Default value is High level logging when creating or running an ad-hoc command in FMS Explorer or via the FMS in CygNet Explorer.

Command Parameters

The following command parameters apply to Request New Data commands, when scheduling, creating, or editing commands via CygNet Explorer or scripting.

Parameter	Description	Type	Usage Notes
ClrTokens	Override data tokens with date/time	DateTime	Specifies the date/time to use to override the data tokens, in order to allow retrieval of data from a specific time. This may be necessary if the device loses power or is reset, resulting in the data tokens becoming invalid. If used, double-click to access the Select Date/Time dialog box. See Note below this table. See Selecting Date and Time for more information. This parameter is optional.
CfgFreq	Configuration request frequency (days)	Integer	If used, double-click to access the Enter Configuration Request Frequency dialog box. Type the request frequency into the text box. Configuration, and product if supported for the Node, record requests will be made based on this frequency. When the request is made, this value will be checked to determine behavior as follows. If no previous request has been made, the data will be requested, irrespective of this value. If this value (in number of days) has passed since the previous request, the data will be requested. If this value is zero (0), the data will be requested. This parameter is optional.
Timeout	Previous request timeout (hours)	Integer	If used, double-click to access the Enter Previous Request Timeout (Hours) dialog box. Type the number of hours before which the request will timeout if it hasn't been completed by the UIS. Each device is only allowed a single outstanding poll (per type) at a time. This parameter is optional.
GetGMHist	Get periodic metering history	String Enum	If used, double-click to access the Get Periodic Metering History dialog box. Select one of the following options. Yes (YES via script) No (NO via script) This parameter is optional. Default value is Yes.
GetGQHist	Get periodic quality history	String Enum	If used, double-click to access the Get Periodic Quality History dialog box. Select one of the following options. Yes (YES via script) No (NO via script) This parameter is optional. Default value is Yes.
GetEvents	Get events history	String Enum	If used, double-click to access the Get Events History dialog box. Select one of the following options. Yes (YES via script) No (NO via script) This parameter is optional. Default value is Yes. See Special FMS Command Notes for more information about requesting alarm and event data.
GetAlarms	Get alarms history	String Enum	If used, double-click to access the Get Alarms History dialog box. Select one of the following options. Yes (YES via script) No (NO via script) This parameter is optional. Default value is Yes. See Special FMS Command Notes for more information about requesting alarm and event data.
GetBatch	Get batch data	String Enum	If used, double-click to access the Get Batch Data dialog box. Select one of the following options. Yes (YES via script) No (NO via script) This parameter is optional. Default value is Yes.
GetTicket	Get ticket data	String Enum	If used, double-click to access the Get Ticket Data dialog box. Select one of the following options. Yes (YES via script) No (NO via script) This parameter is optional. Default value is Yes.
DataGaps	Request missing/unavailable data	String Enum	If used, double-click to access the Request Missing/Unavailable Data dialog box to include additional data in the request. Select one of the following options. Missing and unavailable data (All via script) Missing data only (Missing via script) None (None via script) This parameter is optional. Default value is None.
AddNodeGrp	Add Node to group if unsuccessful	String	If used, double-click to access the Enter Add Node to Group if Unsuccessful dialog box. Enter the name of a valid general group Node to which device Nodes will be added if they fail polling. This facilitates future polling by providing a group containing the device Nodes for which the data request was unsuccessful. See Creating General Group Nodes for more information. Notes: Create the targeted general group Node in advance, naming the group descriptively to clearly identify its data request type. It is recommended to NOT enforce uniqueness when configuring a group Node for this purpose. Review command logs for details of Node additions and/or errors. Manually remove each Node from the polling group once its corresponding data request has succeeded. This parameter is optional.

Note: Date/time — When using relative (rather than absolute) date/time, if both the start and end date/time have hour, minute, and second values of 00 (or if both are set to midnight), an additional day will be added to the date at the end of the range. This occurs because the service assumes the start of the day for the starting date/time and the end of the day for the ending date/time in these circumstances. Therefore requesting a time range from T to T will yield one day of data, and from T-1 to T will yield two days of data. If only one day of data is desired when using relative date/time, the start and end date/times must therefore be the same. If any of the start or end date/time hour, minute, or second values are specified as a value other than zero (or midnight) however, the range will be used as specified.